RESTful Engine API Tutorial: The Full Process Using the RESTful API

In this tutorial, we will build off on what we did in the last tutorial. We will step through the complete procedure of the document generation process so you can see it in action, and learn the proper way to interact with the RESTful Engine once you set it up for production. Again for this tutorial, the template and data file are included in the predefined request body on SwaggerHub. You can find this on the Getting Started with the RESTful API Page.

Once you setup your RESTful Engine and it starts processing heavier loads (larger templates, multiple users sending requests at the same time, or just running many different requests simultaneously in general), you will need to check the status of the document before you can retrieve it. In this tutorial we will step through the different endpoints you will need to post the template, check the document generation status, and finally get the document successfully.

What You Need

All you need to complete this tutorial is a trial license key which you can get from our website.

Testing Out the Full Process

1. Navigate to our SwaggerHub API
2. You will need to enter your trial license key. To do so, click on the "Authorize" button at the top of the API documentation:

note

Setting the license key as described above will set the "X-WINDWARD-LICENSE" header for all the endpoints in our SwaggerHub documentation, so it sends your license key with each request in the headers.

3. Enter your trial key, then click Authorize:

Now we are ready to post our template. Here is the outline of the steps required to post, and get a document after its done processing:

• POST the template we wish to process
• GET the document status, here are the following statuses you might get:
  • 201 - Created
  • 202 - Processing
  • 302 - Completed Processing
  • 404 - The requested output doe not exist
  • 500 - There was an error processing the document
• When we get back a 302 status, we can now GET the processed document

4. Now we POST the template we want to process. Navigate to the "Documents" section in the API documentation, then expand the POST /v2/document endpoint, this is what you will see:

5. Click on the "Try it out" button:

The text encompassed in the RED rectangle is your Request Body. In the request body we specify everything from the template we are using, to the data sources we are using to the output format we want. We provided you with a complete request body for testing. As you can see, this template is making use of a JSON data source.

6. After you've taken a look at the request body, click the "Execute" button to send the POST request. After sending the request, scroll down a bit and you will see the response from the engine:

note

The response from the RESTful engine will be under "Server response" (highlighted above). The "Code" is the response code, and the "Details" include the response body from the engine.

Make sure to copy the "Guid" from the response. The GUID is a unique identifier we use for the documents being processed, so we will need it to check on the status of the document in the next step.

7. Now that we have posted the template for processing, we now need to check on the processing status of the document. To do this, find the "GET /v2/document/{GUID}/status" endpoint. Expand it and click the "Try it out" button:

Paste the GUID you copied in step 7, and then click "Execute". If the document is done processing you will get the following response:

Where it says that the server response is "Code 302" (as highlighted above). If you get a 201 or a 202 response code, wait 10 seconds and execute the get request again until it returns a response code of 302.

caution

Note there is a bug in Swagger where it describes a successful response code of 302 as an error (as seen in the red rectangle above). Ignore that, 302 is a successful response code.

8. Now that our document is done processing, it is ready to retrieve. You can either download the generated document via the address you used in the previous tutorial:

http://ec2-34-201-126-96.compute-1.amazonaws.com/v2/document/{YOUR_GUID_HERE}/file

Or you can GET the document as a JSON object . To do so, navigate to the "GET /v2/document/{GUID} endpoint. Click the "Try it out" button:

Enter the GUID from the earlier steps, then click Execute. This will return your completed document in the response body:

The completed document is encoded in base64 in the "Data" section of the response body. In order to get the actual document, you can decode the data using an online decoder like this one.

Now you are done! You have successfully posted and retrieved a document after it was done processing. Read the next section for some next steps as you learn how to use our RESTful engine.

The Full Process Recap

To summarize the process we just went through, here is a list of the endpoints that we made use of in the order in which they were used:

1. POST /v2/document
   • This endpoint posts our template to the RESTful Engine. If successful, the engine will return a GUID for the document which will be used to check the status of the document, and later retrieve the document
2. GET /v2/document/{GUID}/status
   • This endpoint will retrieve the status of the document via the GUID. When know the document is done processing and is ready to retrieve when we receive response code 302
3. Lastly we retrieved the generated document using two endpoints:

   - `GET /v2/document/{GUID}`
       - This endpoint retrieved the generated document as a JSON object.
   - `{YOUR_RESTFUL_ADDRESS}/v2/document/{GUID}/file`
       - This endpoint downloaded the generated document in your browser
   These are the steps you should generally follow when interacting with the RESTful Engine.

RESTful Engine Tutorial: Next Steps

Now that you are more familiar with the document generation process, we recommend stepping through the following tutorials that will help you put together your own request body; one using connection strings, the other using base64 encoded data:

• RESTful Engine API Tutorial: Constructing Simple Request Bodies Using Connection Strings
• RESTful Engine API Tutorial: Constructing Simple Request Bodies Using Base64 Encoded Data

If you are ready to setup your own RESTful engine, check out how to setup your own RESTful engine here:

• .NET RESTful Engine
• Java RESTful Engine